home *** CD-ROM | disk | FTP | other *** search
/ SGI Hot Mix 17 / Hot Mix 17.iso / HM17_SGI / research / lib / obsolete / gethelp.pro < prev    next >
Encoding:
Text File  |  1997-07-08  |  14.7 KB  |  491 lines
  1. ; $Id: gethelp.pro,v 1.3 1997/01/15 04:02:19 ali Exp $
  2. ;
  3. ; Copyright (c) 1993-1997, Research Systems, Inc.  All rights reserved.
  4. ;       Unauthorized reproduction prohibited.
  5. ;
  6. ;+
  7. ; NAME:
  8. ;     GETHELP
  9. ;
  10. ; PURPOSE:
  11. ;    This function is used to get information on variables in the 
  12. ;    routine that called this function. The function builts a string array
  13. ;    that contains information that follows the format that is used
  14. ;    by the IDL HELP command. 
  15. ;
  16. ; CATEGORY:
  17. ;    Help
  18. ;
  19. ; CALLING SEQUENCE:
  20. ;    Result = GetHelp([Vname])
  21. ;
  22. ; INPUTS:
  23. ;    Vname:    Optional parameter that contains the name of a variable
  24. ;        the user wants information about.
  25. ;
  26. ; KEYWORD PARAMETERS:
  27. ;    ONELINE:    If a variable name is greater than 15 charaters
  28. ;            it is usally returned as 2 two elements of the
  29. ;            output array (Variable name in 1st element, 
  30. ;            variable info in the 2nd element). Setting this 
  31. ;            keyword will put all the information in one string,
  32. ;            seperating the name and  data with a space.
  33. ;
  34. ;    FULLSTRING:    Normally a string that is longer than 45 chars
  35. ;            is truncated and followed by "..." just like 
  36. ;            the HELP command. Setting this keyword will cause
  37. ;            the full string to be returned.
  38. ;
  39. ;    PROCEDURES:    Setting this keyword will cause the function
  40. ;            to return all current IDL compiled procedures.
  41. ;
  42. ;    FUNCTIONS:    Setting this keyword will cause the function
  43. ;            to return all current IDL compiled functions.
  44. ;
  45. ;    SYS_PROCS:    Setting this keyword will cause the function
  46. ;            to return the names of all IDL system (built-in)
  47. ;            procedures.
  48. ;
  49. ;    SYS_FUNCS:    Setting this keyword will cause the function
  50. ;            to return the names of all IDL system (built-in)
  51. ;            functions.
  52. ;
  53. ; OUTPUTS:
  54. ;    This function returns a string array that normally contains
  55. ;    variable data that is in the same format as used by the IDL HELP
  56. ;    procedure. The variables in this list are for the routine that
  57. ;    called GetHelp(). If other info is requested via keywords, this
  58. ;    data is returned.
  59. ;
  60. ;    Upon an error or if no data is found the function returns an 
  61. ;    Null ('') string. 
  62. ;
  63. ; COMMON BLOCKS:
  64. ;    None
  65. ;
  66. ; SIDE EFFECTS:
  67. ;    None
  68. ;
  69. ; RESTRICTIONS:
  70. ;    Due to the diffuculties in determining if a variable is of type
  71. ;    associate, the following conditions will result in the variable 
  72. ;    being listed as a structure. These conditions are:
  73. ;
  74. ;         o Associate record type is structure.
  75. ;        o Associated file is opened for update (openu).
  76. ;        o Associate file is not empty.
  77. ;
  78. ;       Another difference between this routine and the IDL help command
  79. ;    is that if a variable is in a common block, the common block name 
  80. ;    is not listed next to the variable name. Currently there is no
  81. ;    method available to get the common block names used in a routine.
  82. ;
  83. ; PROCEDURE:
  84. ;    This function uses the IDL routine Routine_Names() to get the 
  85. ;    names and values of the variables contained in the calling 
  86. ;    routine. These values are then placed in a string array using
  87. ;    the format of the IDL HELP command. If there are no variables
  88. ;    in the calling routine, a null ('') scalar string is returned.
  89. ;
  90. ; EXAMPLE:
  91. ;    To obtain a listing in a help "format" of the variables contained
  92. ;    in the current routine you would make the following call:
  93. ;
  94. ;        HelpData = GetHelp()
  95. ;
  96. ;    The variable HelpData would be a string array containing the 
  97. ;    requested information.
  98. ;
  99. ; MODIFICATION HISTORY:
  100. ;    Initial Coding  April 1994    - KDB
  101. ;
  102. ;-
  103. ;
  104. ;=============================================================================
  105.  
  106.    FUNCTION IS_ASSOC, Unit
  107.  
  108. ; PURPOSE:
  109. ;    This function is used to determine if an IDL variable is a
  110. ;    Assoc() file variable. This function is needed since there is no
  111. ;    built in method for a program to determine if a variable is an
  112. ;    associated variable.
  113. ;
  114. ; OPERATION:
  115. ;    This functions depends on several properities of an associate 
  116. ;    variable to determine if a variable is one. These properties are:
  117. ;
  118. ;       o Size indicates that an associate variable is an array
  119. ;       o N_Elements always returns one for an associate variable
  120. ;       o ON_IOERROR will trap I/O errors that happen during associate
  121. ;         file operations.
  122. ;       o The following command will result in a scalar for a normal
  123. ;         array, an array for an associate variable:
  124. ;         DUM = Var(0)
  125. ;      
  126. ; RESTRICTIONS:
  127. ;    Due to the diffuculties in determining if a variable is of type
  128. ;    associate, the following conditions will result in this function 
  129. ;    returning a false. These conditions are:
  130. ;
  131. ;         o Associate record type is structure.
  132. ;        o Associated file is opened for update (openu).
  133. ;        o Associate file is not empty.
  134. ;
  135. ; Start by getting the size of the input parameter
  136.  
  137.   UnitSize = Size(Unit)
  138.  
  139. ; All Assocs are arrays and N_Elements() only returns 1. Check if this 
  140. ; variable is a scalar or N_elements() > 1.
  141.  
  142.   if((UnitSize(0) eq 0)or(N_Elements(Unit) gt 1))then $
  143.      Return, 0  ; no need to continue
  144.  
  145. ; Set up Error handling for input/ouput. This will catch any errors I/O we
  146. ; cause with associate variables. This function depends on this trapping.
  147.  
  148.   On_IOerror, IOERR
  149.  
  150. ; Set the first element of Unit equal to itself. If Unit is an array we
  151. ; will continue processing, but if Unit is an associate variable and the 
  152. ; file is not open for "update" we will trigger an error which is trapped
  153. ; by on_ioerror.
  154.  
  155.   Unit(0) = Unit(0)
  156.  
  157. ; A single diminsion array would of passed the above test, see if we
  158. ; can get the first value of Unit.
  159.  
  160.   DumVal = Unit(0)
  161.   
  162. ; Get the Size of DumVal
  163.  
  164.   DumSize = Size(DumVal)
  165.  
  166. ; If DumVal is a scalar (So Unit was a 1 dim array) or if DumVal is a 
  167. ; struct (so Unit is a struct or assoc to a struct record opened for update)
  168. ; return a false.
  169.  
  170.   if((DumSize(0) eq 0)or(DumSize(N_Elements(DumSize)-2) eq 8))then $
  171.     Return, 0
  172.  
  173. ; The only type of variable that should get here is an associate variable.
  174. ; Get the file information for this variable
  175.  
  176.    UnitStat = Fstat(Unit)
  177.  
  178. ; Make sure that the file is not a tty or has no name
  179.  
  180.   if((UnitStat.IsAtty eq 1)or(UnitStat.Name eq ''))then  $
  181.        return,0     ;not an assoc
  182.  
  183. ; Anything that gets below this point is an associate variable 
  184.  
  185. IOERR:
  186.  
  187.   Return, 1  ; it is an assoc() variable
  188.  
  189. END
  190.  
  191. ;=============================================================================
  192.  
  193.  FUNCTION MakeHelpString, Vname, Vvalue, Vsize, ASSOC = ASSOC, $
  194.                ONELINE=ONELINE, FULLSTRING=FULLSTRING
  195.  
  196. ; PURPOSE:
  197. ;    This function takes information about a variable and creates
  198. ;    a string that contains this information following the IDL HELP
  199. ;    format.
  200. ;
  201. ; INPUTS:
  202. ;    Vname:        The name of the Variable
  203. ;    Vvalue:        The actual value of the variable
  204. ;    Vsize;        The results of the Size() function on Vvalue
  205. ;
  206. ; KEYWORD PARAMETERS:
  207. ;    ASSOC:        Indicates that the variable is an Associate 
  208. ;            variable
  209. ;    
  210. ;    ONELINE:    If a variable name is greater than 15 charaters
  211. ;            it is usally returned as 2 a two element array 
  212. ;            (Variable name in 1st elements, Variable info
  213. ;            in the 2nd element). Setting this keyword
  214. ;            will put all the information in one string.
  215. ;
  216. ;    FULLSTRING:    Normally a string that is longer than 45 chars
  217. ;            is truncated and followed by "..." just like 
  218. ;            the HELP command. Setting this keyword will cause
  219. ;            the full string to be returned.
  220. ;
  221. ; OUTPUTS:
  222. ;    This function returns a string(s) that is in a HELP command format
  223. ;    for the given information. A 2 element string array is returned if
  224. ;    the Variable name (Vname) is longer that 15 characters and the
  225. ;    ONELINE keyword is not set.
  226. ;
  227. ; Declare the TypeTokens
  228.  
  229.   TypeTokens = [ 'UNDEFINED', 'BYTE', 'INT', 'LONG', 'FLOAT', $
  230.          'DOUBLE', 'COMPLEX', 'STRING', 'STRUCT']
  231.  
  232.   Vtype = Vsize(N_Elements(Vsize)-2) ; Get the type of variable
  233.  
  234. ; See if the variable is not an array (a Scalar or an Undef).
  235.  
  236.   if( Vsize(0) eq 0 )then BEGIN
  237.    
  238.   ; If the Value is a string we need to put '' around it and add ... to it
  239.   ; if it is longer than 45 chars
  240.  
  241.     if(Vtype eq 7)then BEGIN
  242.  
  243.        if( (StrLen(Vvalue) gt 45)and(not Keyword_Set(FULLSTRING)))then  $
  244.        ValueField = "'" + StrMid(Vvalue, 0, 45) + "'..."              $
  245.        else        $
  246.        ValueField = "'" + Vvalue +"'"
  247.  
  248.     ENDif else if(Vtype eq 1)then  $  
  249.     ;  have a byte, cant just string it, use integer format code 
  250.  
  251.        ValueField = String(Vvalue, FORMAT='(I4)')    $
  252.  
  253.     else    $   ;not a string or a byte, just do a String() to the value
  254.  
  255.        ValueField = String(Vvalue)      
  256.  
  257.   ENDif else     $                           
  258.   ;  We have an array, convert the diminsions of the array to strings
  259.   ;  The format statement has a repeat value of 20. Should only need up
  260.   ;  to 8 (the max number of dimensions, but doesnt hurt to have a little
  261.   ;  extra just incase this changes later on.
  262.  
  263.      ValueField= String( StrCompress(Vsize(1:Vsize(0)), /REMOVE_ALL), $
  264.                 FORMAT = '("Array(",20(a, :, ", ") )' ) +")"
  265.  
  266. ; Now check out the Assoc() variable possibility
  267.  
  268.   if(Keyword_Set(ASSOC))then BEGIN
  269.  
  270.   ;  Need to get the filename associated with the variable. Fstat() it.
  271.  
  272.      StatStruc = Fstat(Vvalue)
  273.   
  274.   ;  An Assoc() can be done on a file that is not open. See if the 
  275.   ;  name is null. If file is closed (name =''), put in HELP closed message
  276.  
  277.      if(StatStruc.Name eq '')then             $
  278.     StatStruc.Name = "Closed file unit "+ $
  279.         StrCompress(StatStruc.Unit, /REMOVE_ALL)
  280.  
  281.      ValueField = "File<"+StatStruc.Name+"> "+ValueField
  282.  
  283.   ENDif
  284.  
  285. ; Is the data a structure?
  286.  
  287.   if(Vtype eq 8)then                 $
  288.   ;  Add the struct symbol and name to Value Field
  289.      
  290.      ValueField = "-> " + Tag_Names(Vvalue, /STRUCTURE_NAME)+ " " + $
  291.               ValueField
  292.     
  293. ; Now lets build the line and return it. Check for long identifiers
  294.  
  295.   if( StrLen(Vname) gt 15)then BEGIN
  296.   ;  We have a long indentifier. See if the user want the line on one line
  297.   ;  or 2
  298.    
  299.      if(Keyword_Set(ONELINE))then                 $
  300.     Return, Vname + String(TypeTokens(Vtype), ValueField,     $
  301.             FORMAT='(" ", A, T11,"= ", A)' )      $
  302.      else                            $
  303.     Return, [Vname, String(TypeTokens(Vtype), ValueField,   $
  304.             FORMAT='(T16," ", A,T27,"= ", A)' )] 
  305.   ENDif 
  306.  
  307. ; Variable name must be < 15 chars. Just return the old fashioned type 
  308. ; of listing
  309.  
  310.   Return, String(Vname, TypeTokens(Vtype), ValueField,$
  311.          FORMAT= '(A,T16," ", A,T27,"= ", A)' )
  312.  
  313. END
  314. ;=============================================================================
  315.  
  316.   FUNCTION Gethelp, Uservar, ONELINE=ONELINE, PROCEDURES=PROCEDURES, $
  317.            FUNCTIONS = FUNCTIONS, SYS_PROCS=SYS_PROCS,       $
  318.            SYS_FUNCS=SYS_FUNCS, FULLSTRING=FULLSTRING
  319.  
  320. ; PURPOSE:
  321. ;    This function is used to get information on variables in the 
  322. ;    routine that called this function. The function builts a string array
  323. ;    that contains information that follows the format that is 
  324. ;    printed out by the IDL HELP command. 
  325. ;
  326. ; CALLING SEQUENCE:
  327. ;    Result = GetHelp([Vname])
  328. ;
  329. ; INPUTS:
  330. ;    Vname:    Optional parameter that contains the name of a variable
  331. ;        the user wants information about.
  332. ;
  333. ; KEYWORD PARAMETERS:
  334. ;    ONELINE:    If a variable name is greater than 15 charaters
  335. ;            it is usally returned as 2 two elements of the
  336. ;            output array (Variable name in 1st elements, 
  337. ;            Variable info in the 2nd element). Setting this 
  338. ;            keyword will put all the information in one string,
  339. ;            seperating the name and  data with a space.
  340. ;
  341. ;    FULLSTRING:    Normally a string that is longer than 45 chars
  342. ;            is truncated and followed by "..." just like 
  343. ;            the HELP command. Setting this keyword will cause
  344. ;            the full string to be returned.
  345. ;
  346. ;    PROCEDURES:    Setting this keyword will cause the function
  347. ;            to return all current IDL compiled procedures.
  348. ;
  349. ;    FUNCTIONS:    Setting this keyword will cause the function
  350. ;            to return all current IDL compiled functions.
  351. ;
  352. ;    SYS_PROCS:    Setting this keyword will cause the function
  353. ;            to return the names of all IDL system (built-in)
  354. ;            procedures.
  355. ;
  356. ;    SYS_FUNCS:    Setting this keyword will cause the function
  357. ;            to return the names of all IDL system (built-in)
  358. ;            functions.
  359. ;
  360. ; OUTPUTS:
  361. ;    This function returns a string array that normally contains
  362. ;    variable data that is in the same format as used by the IDL HELP
  363. ;    procedure. The variables in this list are for the routine that
  364. ;    called GetHelp(). If other info is requested via keywords, this
  365. ;    data is returned.
  366. ;
  367. ;    Upon an error the function returns an Null ('') string. 
  368. ;
  369. ;
  370. ; See if the user just wants the names of routines or functions:
  371.  
  372.   if(Keyword_Set(PROCEDURES))then  $
  373.      Return, Routine_Names(PROCEDURES=-1)
  374.  
  375.   if(Keyword_Set(FUNCTIONS))then   $
  376.      Return, Routine_Names(FUNCTIONS=-1 )
  377.  
  378. ; See if the user wants the system procedure names
  379.  
  380.   if(Keyword_Set(SYS_PROCS))then   $
  381.      Return, Routine_Names(S_PROCEDURES=-1)
  382.  
  383. ; And now check for system functions
  384.  
  385.   if(Keyword_Set(SYS_FUNCS))then   $
  386.      Return, Routine_Names(S_FUNCTIONS=-1)
  387.  
  388. ; Start by getting the variable names for the calling procedure
  389.  
  390.   VarNames = Routine_Names(VARIABLES=-1)
  391.  
  392. ; See if we got any variables. 
  393.  
  394.   NumVars = N_Elements(VarNames) ; number of variables 
  395.  
  396.   if( NumVars eq 1)then $
  397.      if(VarNames(0) eq '')then $
  398.     Return,''        ;No Variables, Why continue?
  399.  
  400. ; Check for a parameter
  401.  
  402.   if(N_Params() eq 1)then BEGIN
  403.  
  404.   ; The user wants the help value for just one variable, See if it 
  405.   ; is in the list of valid variables.
  406.  
  407.     Vindx = Where(StrUpcase(UserVar) eq VarNames, Vcnt)
  408.  
  409.     if(Vcnt eq 1)then BEGIN
  410.  
  411.     ; Just place this variable in place of the found variables
  412.  
  413.       VarNames = VarNames(Vindx)
  414.       NumVars = 1
  415.  
  416.     ENDif else Return,''  ; not a valid variable
  417.  
  418.   ENDif
  419.  
  420. ; Initialize the value of OutText. Check for long parameters.
  421. ; For each long parameter ( >15 chars), add a line to the OutText Array. 
  422. ; Only check this is if keyword ONELINE is set.
  423.  
  424.   LongCnt = 0
  425.   if( not KeyWord_Set(ONELINE))then $
  426.       tmp = Where(StrLen(VarNames) gt 15, LongCnt)
  427.   
  428.   OutText = Strarr(NumVars + LongCnt )
  429.   OutCnt = 0 & tmp = 0
  430.  
  431. ; Now loop though each variable, get its value, format its help string and
  432. ; place the string into the OutText array.
  433.  
  434.   for i=0, NumVars-1 do BEGIN
  435.  
  436.   ;  Get the *size* of the variable value. This will also handle udefs.
  437.  
  438.      VarSize = Size(Routine_Names( VarNames(i), FETCH=-1) )
  439.  
  440.   ;  If the variable is not of type undefined, get its value
  441.  
  442.      if( VarSize(N_Elements(VarSize)-2) ne 0 )then         $ ;not undef
  443.     VarValue = Routine_Names( VarNames(i), FETCH=-1 )     $
  444.      else                             $
  445.     VarValue = '<Undefined>'   ;From help output
  446.  
  447.   ;  See if the variable is an Assoc() variable. If the variable is 
  448.   ;  an array or struct it might be.
  449.  
  450.      if( VarSize(0) gt 0 )then        $  ;not undefined and not a scalar
  451.         ASSOC = IS_ASSOC( VarValue )  $  ; ? is it an Assoc()
  452.      else                      $
  453.         ASSOC = 0    ;no an associate variable
  454.  
  455.   ;  Now send the variable name, value and size to MakeHelpString
  456.  
  457.      TmpTxt = MakeHelpString(VarNames(i), VarValue, VarSize, $
  458.           ASSOC=ASSOC, ONELINE=ONELINE, FULLSTRING=FULLSTRING ) 
  459.  
  460.   ;  Place the results in OutText
  461.   ;  Could use [ ] to append, but with large arrays this can be slow.
  462.  
  463.      OutText(OutCnt) = TmpTxt   ; overload index if need be (TmpTxt is 2 el.)
  464.      OutCnt = OutCnt + N_Elements(TmpTxt)
  465.  
  466.   ENDfor
  467.  
  468. ; That should be it, return the array.
  469.  
  470.   Return, OutText
  471.  
  472. END
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.